home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet internetowy / Anonimowosc i bezpieczenstwo / TOR 0.1.1.24 / vidalia-bundle-0.1.1.24-0.0.7.exe / Tor / Documents / rend-spec.txt < prev    next >
Text File  |  2006-09-24  |  21KB  |  450 lines
  1. $Id: rend-spec.txt 5909 2006-02-04 20:07:45Z arma $
  2.  
  3.                     Tor Rendezvous Specification
  4.  
  5. 0. Overview and preliminaries
  6.  
  7.    Read http://tor.eff.org/doc/design-paper/tor-design.html#sec:rendezvous
  8.    before you read this specification. It will make more sense.
  9.  
  10.    Rendezvous points provide location-hidden services (server
  11.    anonymity) for the onion routing network. With rendezvous points,
  12.    Bob can offer a TCP service (say, a webserver) via the onion
  13.    routing network, without revealing the IP of that service.
  14.  
  15.    Bob does this by anonymously advertising a public key for his
  16.    service, along with a list of onion routers to act as "Introduction
  17.    Points" for his service.  He creates forward circuits to those
  18.    introduction points, and tells them about his public key.  To
  19.    connect to Bob, Alice first builds a circuit to an OR to act as
  20.    her "Rendezvous Point." She then connects to one of Bob's chosen
  21.    introduction points, optionally provides authentication or
  22.    authorization information, and asks it to tell him about her Rendezvous
  23.    Point (RP).  If Bob chooses to answer, he builds a circuit to her
  24.    RP, and tells it to connect him to Alice.  The RP joins their
  25.    circuits together, and begins relaying cells.  Alice's 'BEGIN'
  26.    cells are received directly by Bob's OP, which passes data to
  27.    and from the local server implementing Bob's service.
  28.  
  29.    Below we describe a network-level specification of this service,
  30.    along with interfaces to make this process transparent to Alice
  31.    (so long as she is using an OP).
  32.  
  33. 0.1. Notation, conventions and prerequisites
  34.  
  35.    In the specifications below, we use the same notation as in
  36.    "tor-spec.txt".  The service specified here also requires the
  37.    existence of an onion routing network as specified in that file.
  38.  
  39.         H(x) is a SHA1 digest of x.
  40.         PKSign(SK,x) is a PKCS.1-padded RSA signature of x with SK.
  41.         PKEncrypt(SK,x) is a PKCS.1-padded RSA encryption of x with SK.
  42.         Public keys are all RSA, and encoded in ASN.1.
  43.         All integers are stored in network (big-endian) order.
  44.         All symmetric encryption uses AES in counter mode, except where
  45.             otherwise noted.
  46.  
  47.    In all discussions, "Alice" will refer to a user connecting to a
  48.    location-hidden service, and "Bob" will refer to a user running a
  49.    location-hidden service.
  50.  
  51. 0.2. Protocol outline
  52.  
  53.    1. Bob->Bob's OP: "Offer IP:Port as
  54.       public-key-name:Port". [configuration]
  55.       (We do not specify this step; it is left to the implementor of
  56.       Bob's OP.)
  57.  
  58.    2. Bob's OP generates keypair and rendezvous service descriptor:
  59.         "Meet public-key X at introduction point A, B, or C." (signed)
  60.  
  61.    3. Bob's OP->Introduction point via Tor: [introduction setup]
  62.         "This pk is me."
  63.  
  64.    4. Bob's OP->directory service via Tor: publishes Bob's service
  65.       descriptor [advertisement]
  66.  
  67.    5. Out of band, Alice receives a [x.y.]z.onion:port address.
  68.       She opens a SOCKS connection to her OP, and requests
  69.       x.y.z.onion:port.
  70.  
  71.    6. Alice's OP retrieves Bob's descriptor via Tor. [descriptor lookup.]
  72.  
  73.    7. Alice's OP chooses a rendezvous point, opens a circuit to that
  74.       rendezvous point, and establishes a rendezvous circuit. [rendezvous
  75.       setup.]
  76.  
  77.    8. Alice connects to the Introduction point via Tor, and tells it about
  78.       her rendezvous point and optional authentication/authorization
  79.       information.  (Encrypted to Bob.)  [Introduction 1]
  80.  
  81.    9. The Introduction point passes this on to Bob's OP via Tor, along the
  82.       introduction circuit. [Introduction 2]
  83.  
  84.   10. Bob's OP decides whether to connect to Alice, and if so, creates a
  85.       circuit to Alice's RP via Tor.  Establishes a shared circuit.
  86.       [Rendezvous.]
  87.  
  88.   11. Alice's OP sends begin cells to Bob's OP.  [Connection]
  89.  
  90. 0.3. Constants and new cell types
  91.  
  92.   Relay cell types
  93.       32 -- RELAY_ESTABLISH_INTRO
  94.       33 -- RELAY_ESTABLISH_RENDEZVOUS
  95.       34 -- RELAY_INTRODUCE1
  96.       35 -- RELAY_INTRODUCE2
  97.       36 -- RELAY_RENDEZVOUS1
  98.       37 -- RELAY_RENDEZVOUS2
  99.       38 -- RELAY_INTRO_ESTABLISHED
  100.       39 -- RELAY_RENDEZVOUS_ESTABLISHED
  101.       40 -- RELAY_COMMAND_INTRODUCE_ACK
  102.  
  103. 1. The Protocol
  104.  
  105. 1.1. Bob configures his local OP.
  106.  
  107.    We do not specify a format for the OP configuration file.  However,
  108.    OPs SHOULD allow Bob to provide more than one advertised service
  109.    per OP, and MUST allow Bob to specify one or more virtual ports per
  110.    service.  Bob provides a mapping from each of these virtual ports
  111.    to a local IP:Port pair.
  112.  
  113. 1.2. Bob's OP generates service descriptors.
  114.  
  115.    The first time the OP provides an advertised service, it generates
  116.    a public/private keypair (stored locally).  Periodically, the OP
  117.    generates a pair of service descriptors, one "V1" and one "V0".
  118.  
  119.    The "V1" descriptor in 0.1.1.6-alpha contains:
  120.  
  121.          V     Format byte: set to 255               [1 octet]
  122.          V     Version byte: set to 1                [1 octet]
  123.          KL    Key length                            [2 octets]
  124.          PK    Bob's public key                      [KL octets]
  125.          TS    A timestamp                           [4 octets]
  126.          PROTO Rendezvous protocol versions: bitmask [2 octets]
  127.          NA    Number of auth mechanisms accepted    [1 octet]
  128.          For each auth mechanism:
  129.              AUTHT  The auth type that is supported  [2 octets]
  130.              AUTHL  Length of auth data              [1 octet]
  131.              AUTHD  Auth data                        [variable]
  132.          NI    Number of introduction points         [2 octets]
  133.          For each introduction point: (as in INTRODUCE2 cells)
  134.              ATYPE  An address type (typically 4)    [1 octet]
  135.              ADDR   Introduction point's IP address  [4 or 16 octets]
  136.              PORT   Introduction point's OR port     [2 octets]
  137.              AUTHT  The auth type that is supported  [2 octets]
  138.              AUTHL  Length of auth data              [1 octet]
  139.              AUTHD  Auth data                        [variable]
  140.              ID     Introduction point identity ID   [20 octets]
  141.              KLEN   Length of onion key              [2 octets]
  142.              KEY    Introduction point onion key     [KLEN octets]
  143.          SIG   Signature of above fields             [variable]
  144.  
  145.    The "V1" descriptor in 0.1.1.5-alpha-cvs contains:
  146.  
  147.          V     Format byte: set to 255               [1 octet]
  148.          V     Version byte: set to 1                [1 octet]
  149.          KL    Key length                            [2 octets]
  150.          PK    Bob's public key                      [KL octets]
  151.          TS    A timestamp                           [4 octets]
  152.          PROTO Protocol versions: bitmask            [2 octets]
  153.          NI    Number of introduction points         [2 octets]
  154.          For each introduction point: (as in INTRODUCE2 cells)
  155.              IP     Introduction point's address     [4 octets]
  156.              PORT   Introduction point's OR port     [2 octets]
  157.              ID     Introduction point identity ID   [20 octets]
  158.              KLEN   Length of onion key              [2 octets]
  159.              KEY    Introduction point onion key     [KLEN octets]
  160.          SIG   Signature of above fields             [variable]
  161.  
  162.    The "V0" descriptor contains:
  163.  
  164.          KL    Key length                            [2 octets]
  165.          PK    Bob's public key                      [KL octets]
  166.          TS    A timestamp                           [4 octets]
  167.          NI    Number of introduction points         [2 octets]
  168.          Ipt   A list of NUL-terminated ORs          [variable]
  169.          SIG   Signature of above fields             [variable]
  170.  
  171.    KL is the length of PK, in octets.
  172.    TS is the number of seconds elapsed since Jan 1, 1970.
  173.  
  174.    AUTHT specifies which authentication/authorization mechanism is
  175.    required by the hidden service or the introduction point. AUTHD
  176.    is arbitrary data that can be associated with an auth approach.
  177.    Currently only AUTHT of [00 00] is supported, with an AUTHL of 0.
  178.    See section 2 of this document for details on auth mechanisms.
  179.  
  180.    The members of Ipt may be either (a) nicknames, or (b) identity key
  181.    digests, encoded in hex, and prefixed with a '$'.  Clients must
  182.    accept both forms. Services must only generate the second form.
  183.    Once 0.0.9.x is obsoleted, we can drop the first form.
  184.  
  185.    [It's ok for Bob to advertise 0 introduction points. He might want
  186.     to do that if he previously advertised some introduction points,
  187.     and now he doesn't have any. -RD]
  188.  
  189.    [Once Tor 0.1.0.x is obsolete, we can stop generating or using V0
  190.     descriptors. -NM]
  191.  
  192. 1.3. Bob's OP establishes his introduction points.
  193.  
  194.    The OP establishes a new introduction circuit to each introduction
  195.    point.  These circuits MUST NOT be used for anything but rendezvous
  196.    introduction.  To establish the introduction, Bob sends a
  197.    RELAY_ESTABLISH_INTRO cell, containing:
  198.  
  199.         KL   Key length                             [2 octets]
  200.         PK   Bob's public key                       [KL octets]
  201.         HS   Hash of session info                   [20 octets]
  202.         SIG  Signature of above information         [variable]
  203.  
  204.    [XXX011, need to add auth information here. -RD]
  205.  
  206.    To prevent replay attacks, the HS field contains a SHA-1 hash based on the
  207.    shared secret KH between Bob's OP and the introduction point, as
  208.    follows:
  209.        HS = H(KH | "INTRODUCE")
  210.    That is:
  211.        HS = H(KH | [49 4E 54 52 4F 44 55 43 45])
  212.    (KH, as specified in tor-spec.txt, is H(g^xy | [00]) .)
  213.  
  214.    Upon receiving such a cell, the OR first checks that the signature is
  215.    correct with the included public key.  If so, it checks whether HS is
  216.    correct given the shared state between Bob's OP and the OR.  If either
  217.    check fails, the OP discards the cell; otherwise, it associates the
  218.    circuit with Bob's public key, and dissociates any other circuits
  219.    currently associated with PK.  On success, the OR sends Bob a
  220.    RELAY_INTRO_ESTABLISHED cell with an empty payload.
  221.  
  222. 1.4. Bob's OP advertises his service descriptor(s).
  223.  
  224.    Bob's OP opens a stream to each directory server's directory port via Tor.
  225.    (He may re-use old circuits for this.)  Over this stream, Bob's OP makes
  226.    an HTTP 'POST' request, to a URL "/tor/rendezvous/publish" relative to the
  227.    directory server's root, containing as its body Bob's service descriptor.
  228.  
  229.    Bob should upload a service descriptor for each version format that
  230.    is supported in the current Tor network.
  231.  
  232.    Upon receiving a descriptor, the directory server checks the signature,
  233.    and discards the descriptor if the signature does not match the enclosed
  234.    public key.  Next, the directory server checks the timestamp.  If the
  235.    timestamp is more than 24 hours in the past or more than 1 hour in the
  236.    future, or the directory server already has a newer descriptor with the
  237.    same public key, the server discards the descriptor.  Otherwise, the
  238.    server discards any older descriptors with the same public key and
  239.    version format, and associates the new descriptor with the public key.
  240.    The directory server remembers this descriptor for at least 24 hours
  241.    after its timestamp.  At least every 18 hours, Bob's OP uploads a
  242.    fresh descriptor.
  243.  
  244. 1.5. Alice receives a x.y.z.onion address.
  245.  
  246.    When Alice receives a pointer to a location-hidden service, it is as a
  247.    hostname of the form "z.onion" or "y.z.onion" or "x.y.z.onion", where
  248.    z is a base-32 encoding of a 10-octet hash of Bob's service's public
  249.    key, computed as follows:
  250.  
  251.          1. Let H = H(PK).
  252.          2. Let H' = the first 80 bits of H, considering each octet from
  253.             most significant bit to least significant bit.
  254.          2. Generate a 16-character encoding of H', using base32 as defined
  255.             in RFC 3548.
  256.  
  257.    (We only use 80 bits instead of the 160 bits from SHA1 because we
  258.    don't need to worry about arbitrary collisions, and because it will
  259.    make handling the url's more convenient.)
  260.  
  261.    The string "x", if present, is the base-32 encoding of the
  262.    authentication/authorization required by the introduction point.
  263.    The string "y", if present, is the base-32 encoding of the
  264.    authentication/authorization required by the hidden service.
  265.    Omitting a string is taken to mean auth type [00 00].
  266.    See section 2 of this document for details on auth mechanisms.
  267.  
  268.    [Yes, numbers are allowed at the beginning.  See RFC1123. -NM]
  269.  
  270. 1.6. Alice's OP retrieves a service descriptor.
  271.  
  272.    Alice opens a stream to a directory server via Tor, and makes an HTTP GET
  273.    request for the document '/tor/rendezvous/<z>' or '/tor/rendezvous1/<z>',
  274.    where '<z>' is replaced with the encoding of Bob's public key as described
  275.    above. (She may re-use old circuits for this.) The directory replies with
  276.    a 404 HTTP response if it does not recognize <z>, and otherwise returns
  277.    Bob's most recently uploaded service descriptor.  (If Alice requests
  278.    'rendezvous1', the directory server provides a V1 descriptor or a V0
  279.    descriptor if no V1 descriptor is available.  If Alice requests
  280.    'rendezvous', the directory server returns a V0 descriptor.)
  281.  
  282.    If Alice's OP receives a 404 response, it tries the other directory
  283.    servers, and only fails the lookup if none recognize the public key hash.
  284.  
  285.    Upon receiving a service descriptor, Alice verifies with the same process
  286.    as the directory server uses, described above in section 1.4.
  287.  
  288.    The directory server gives a 400 response if it cannot understand Alice's
  289.    request.
  290.  
  291.    Alice should cache the descriptor locally, but should not use
  292.    descriptors that are more than 24 hours older than their timestamp.
  293.    [Caching may make her partitionable, but she fetched it anonymously,
  294.     and we can't very well *not* cache it. -RD]
  295.  
  296. 1.7. Alice's OP establishes a rendezvous point.
  297.  
  298.    When Alice requests a connection to a given location-hidden service,
  299.    and Alice's OP does not have an established circuit to that service,
  300.    the OP builds a rendezvous circuit.  It does this by establishing
  301.    a circuit to a randomly chosen OR, and sending a
  302.    RELAY_ESTABLISH_RENDEZVOUS cell to that OR.  The body of that cell
  303.    contains:
  304.  
  305.         RC   Rendezvous cookie    [20 octets]
  306.  
  307.    [XXX011 this looks like an auth mechanism. should we generalize here? -RD]
  308.  
  309.    The rendezvous cookie is an arbitrary 20-byte value, chosen randomly by
  310.    Alice's OP.
  311.  
  312.    Upon receiving a RELAY_ESTABLISH_RENDEZVOUS cell, the OR associates the
  313.    RC with the circuit that sent it.  It replies to Alice with an empty
  314.    RELAY_RENDEZVOUS_ESTABLISHED cell to indicate success.
  315.  
  316.    Alice's OP MUST NOT use the circuit which sent the cell for any purpose
  317.    other than rendezvous with the given location-hidden service.
  318.  
  319. 1.8. Introduction: from Alice's OP to Introduction Point
  320.  
  321.    Alice builds a separate circuit to one of Bob's chosen introduction
  322.    points, and sends it a RELAY_INTRODUCE1 cell containing:
  323.  
  324.        Cleartext
  325.           PK_ID  Identifier for Bob's PK      [20 octets]
  326. [XXX011 want to put intro-level auth info here, but no version. crap. -RD]
  327.  
  328.        Encrypted to Bob's PK:
  329.           RP     Rendezvous point's nickname  [20 octets]
  330.           RC     Rendezvous cookie            [20 octets]
  331.           g^x    Diffie-Hellman data, part 1 [128 octets]
  332.         OR
  333.           VER    Version byte: set to 1.        [1 octet]
  334.           RP     Rendezvous point nick or ID  [42 octets]
  335.           RC     Rendezvous cookie            [20 octets]
  336.           g^x    Diffie-Hellman data, part 1 [128 octets]
  337.         OR
  338.           VER    Version byte: set to 2.        [1 octet]
  339.           IP     Rendezvous point's address    [4 octets]
  340.           PORT   Rendezvous point's OR port    [2 octets]
  341.           ID     Rendezvous point identity ID [20 octets]
  342.           KLEN  Length of onion key            [2 octets]
  343.           KEY    Rendezvous point onion key [KLEN octets]
  344.           RC     Rendezvous cookie            [20 octets]
  345.           g^x    Diffie-Hellman data, part 1 [128 octets]
  346.         OR
  347.           VER    Version byte: set to 3.           [1 octet]
  348.           ATYPE  An address type (typically 4)     [1 octet]
  349.           ADDR   Introduction point's IP address  [4 or 16 octets]
  350.           PORT   Rendezvous point's OR port       [2 octets]
  351.           AUTHT  The auth type that is supported  [2 octets]
  352.           AUTHL  Length of auth data               [1 octet]
  353.           AUTHD  Auth data                        [variable]
  354.           ID     Rendezvous point identity ID    [20 octets]
  355.           KLEN  Length of onion key               [2 octets]
  356.           KEY    Rendezvous point onion key    [KLEN octets]
  357.           RC     Rendezvous cookie               [20 octets]
  358.           g^x    Diffie-Hellman data, part 1    [128 octets]
  359.  
  360.    PK_ID is the hash of Bob's public key.  RP is NUL-padded and terminated,
  361.    and must contain EITHER a nickname, or an identity key digest, encoded in
  362.    hex, and prefixed with a '$'.
  363.  
  364.    Implementations SHOULD accept all variants, and list the variants they
  365.    accept in their V1 descriptor.  Implementations should only generate the
  366.    variants listed in the service's V1 descriptor; if no V1 descriptor is
  367.    available, only the first variant should be generated.  No version should
  368.    generate the second variant (version byte=1).
  369.  
  370.    The hybrid encryption to Bob's PK works just like the hybrid
  371.    encryption in CREATE cells (see main spec). Thus the payload of the
  372.    RELAY_INTRODUCE1 cell on the wire will contain 20+42+16+20+20+128=246
  373.    bytes. [XXXX not really]
  374.  
  375. 1.9. Introduction: From the Introduction Point to Bob's OP
  376.  
  377.    If the Introduction Point recognizes PK_ID as a public key which has
  378.    established a circuit for introductions as in 1.3 above, it sends the body
  379.    of the cell in a new RELAY_INTRODUCE2 cell down the corresponding circuit.
  380.    (If the PK_ID is unrecognized, the RELAY_INTRODUCE1 cell is discarded.)
  381.  
  382.    After sending the RELAY_INTRODUCE2 cell, the OR replies to Alice with an
  383.    empty RELAY_COMMAND_INTRODUCE_ACK cell.  If no RELAY_INTRODUCE2 cell can
  384.    be sent, the OR replies to Alice with a non-empty cell to indicate an
  385.    error.  (The semantics of the cell body may be determined later; the
  386.    current implementation sends a single '1' byte on failure.)
  387.  
  388.    When Bob's OP receives the RELAY_INTRODUCE2 cell, it decrypts it with
  389.    the private key for the corresponding hidden service, and extracts the
  390.    rendezvous point's nickname, the rendezvous cookie, and the value of g^x
  391.    chosen by Alice.
  392.  
  393. 1.10. Rendezvous
  394.  
  395.    Bob's OP builds a new Tor circuit ending at Alice's chosen rendezvous
  396.    point, and sends a RELAY_RENDEZVOUS1 cell along this circuit, containing:
  397.        RC       Rendezvous cookie  [20 octets]
  398.        g^y      Diffie-Hellman     [128 octets]
  399.        KH       Handshake digest   [20 octets]
  400.  
  401.    (Bob's OP MUST NOT use this circuit for any other purpose.)
  402.  
  403.    If the RP recognizes RC, it relays the rest of the cell down the
  404.    corresponding circuit in a RELAY_RENDEZVOUS2 cell, containing:
  405.  
  406.        g^y      Diffie-Hellman     [128 octets]
  407.        KH       Handshake digest   [20 octets]
  408.  
  409.    (If the RP does not recognize the RC, it discards the cell and
  410.    tears down the circuit.)
  411.  
  412.    When Alice's OP receives a RELAY_RENDEZVOUS2 cell on a circuit which
  413.    has sent a RELAY_ESTABLISH_RENDEZVOUS cell but which has not yet received
  414.    a reply, it uses g^y and H(g^xy) to complete the handshake as in the Tor
  415.    circuit extend process: they establish a 60-octet string as
  416.        K = SHA1(g^xy | [00]) | SHA1(g^xy | [01]) | SHA1(g^xy | [02])
  417.    and generate
  418.        KH = K[0..15]
  419.        Kf = K[16..31]
  420.        Kb = K[32..47]
  421.  
  422.    Subsequently, the rendezvous point passes relay cells, unchanged, from
  423.    each of the two circuits to the other.  When Alice's OP sends
  424.    RELAY cells along the circuit, it first encrypts them with the
  425.    Kf, then with all of the keys for the ORs in Alice's side of the circuit;
  426.    and when Alice's OP receives RELAY cells from the circuit, it decrypts
  427.    them with the keys for the ORs in Alice's side of the circuit, then
  428.    decrypts them with Kb.  Bob's OP does the same, with Kf and Kb
  429.    interchanged.
  430.  
  431. 1.11. Creating streams
  432.  
  433.    To open TCP connections to Bob's location-hidden service, Alice's OP sends
  434.    a RELAY_BEGIN cell along the established circuit, using the special
  435.    address "", and a chosen port.  Bob's OP chooses a destination IP and
  436.    port, based on the configuration of the service connected to the circuit,
  437.    and opens a TCP stream.  From then on, Bob's OP treats the stream as an
  438.    ordinary exit connection.
  439.    [ Except he doesn't include addr in the connected cell or the end
  440.      cell. -RD]
  441.  
  442.    Alice MAY send multiple RELAY_BEGIN cells along the circuit, to open
  443.    multiple streams to Bob.  Alice SHOULD NOT send RELAY_BEGIN cells for any
  444.    other address along her circuit to Bob; if she does, Bob MUST reject them.
  445.  
  446. 2.0. Authentication and authorization.
  447.  
  448. Foo.
  449.  
  450.